Celestin Apprentice 4

home *** CD-ROM | disk | FTP | other *** search

/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Add-Ons / MPW / MPW noweb 2.7 / src / xdoc / notangle.txt < prev next >

Wrap

Text File | 1995-05-30 | 20.2 KB | 463 lines | [????/????]

NOWEB(1) NOWEB(1) NNAAMMEE notangle, noweave, nountangle - noweb, a literate- programming tool SSYYNNOOPPSSIISS nnoottaannggllee [--RRrootname] [--ffiilltteerr command] [--LL[format]] [file] ... nnoouunnttaannggllee [--mmll|--mm33|--cc|--cc++++|--aawwkk|--tteexx|--ff7777|--ff9900] [--RRroot- name] [--ffiilltteerr command] [--wwwidth] [file] ... nnoowweeaavvee [options] [file] ... DDEESSCCRRIIPPTTIIOONN _N_o_w_e_b is a literate-programming tool like Knuth's _W_E_B_, only simpler. A _n_o_w_e_b file contains program source code interleaved with documentation. When _n_o_t_a_n_g_l_e is given a _n_o_w_e_b file, it writes the program on standard output. When _n_o_w_e_a_v_e is given a _n_o_w_e_b file, it reads the _n_o_w_e_b source and produces, on standard output, _L_a_T_e_X, _T_e_X, or _H_T_M_L source for typeset documentation. _n_o_u_n_t_a_n_g_l_e con- verts a literate program into an ordinary program by turn- ing interleaved documentation into comments. The file name `-' refers to standard input. FFOORRMMAATT OOFF NNOOWWEEBB FFIILLEESS A _n_o_w_e_b file is a sequence of _c_h_u_n_k_s_, which may appear in any order. A chunk may contain code or documentation. Documentation chunks begin with a line that starts with an at sign (@) followed by a space or newline. They have no names. Code chunks begin with <<_c_h_u_n_k _n_a_m_e>>= on a line by itself. The double left angle bracket (<<) must be in the first column. Chunks are terminated by the beginning of another chunk, or by end of file. If the first line in the file does not mark the beginning of a chunk, it is assumed to be the first line of a documenta- tion chunk. Documentation chunks contain text that is ignored by _n_o_t_a_n_g_l_e and copied verbatim to standard output by _n_o_w_e_a_v_e (except for quoted code). _n_o_w_e_a_v_e can work with _L_a_T_e_X, plain _T_e_X, or _H_T_M_L. With plain _T_e_X, it inserts a refer- ence to a _T_e_X macro package, _n_w_m_a_c, which defines commands like \\cchhaapptteerr and \\sseeccttiioonn.. Code chunks contain program source code and references to other code chunks. Several code chunks may have the same name; _n_o_t_a_n_g_l_e concatenates their definitions to produce a single chunk, just as does _t_a_n_g_l_e_(_1_)_. Code chunk defini- tions are like macro definitions; _n_o_t_a_n_g_l_e extracts a pro- gram by expanding one chunk (by default, the chunk named <<<<*>>>>). The definition of that chunk contains references to other chunks, which are themselves expanded, and so on. _n_o_t_a_n_g_l_e's output is readable; it preserves the indenta- tion of expanded chunks with respect to the chunks in local 4/19/93 1 NOWEB(1) NOWEB(1) which they appear. Code may be quoted within documentation chunks by placing double square brackets ([[[[_._._.]]]]) around it. These double square brackets are ignored by _n_o_t_a_n_g_l_e_, but they may be used by _n_o_w_e_a_v_e to give the code special typographic treatment, e.g., hypertext links. If quoted code ends with three or more square brackets, _n_o_w_e_a_v_e choose the rightmost pair, so that, for example, [[[[aa[[ii]]]]]] is parsed correctly. If double left and right angle brackets are not paired, they are treated as literal <<<< and >>>>. Users can force any such brackets, even paired brackets, to be treated as literal by using a preceding at sign (e.g. @@<<<<). Any line beginning with `@@ ' terminates a code chunk, but if the line has the form @@ %%ddeeff _i_d_e_n_t_i_f_i_e_r_s it is taken to mean that the preceding chunk defines the identifiers listed in _i_d_e_n_t_i_f_i_e_r_s_. This list contains identifiers separated by whitespace; any sequence of non- white characters may be an identifier. _n_o_w_e_b uses a sim- ple heuristic to avoid recognizing identifiers that are substrings of other identifiers. TTAANNGGLLIINNGG _n_o_t_a_n_g_l_e and _n_o_u_n_t_a_n_g_l_e accept the same set of options, although some options have effects only on one or the other. The options are: --RR_n_a_m_e Expand the <<<<_n_a_m_e>>>> code chunk instead of <<<<*>>>>. --LL_f_o_r_m_a_t Emit line number indications at chunk boundaries. A line number indication identifies the source of the line that follows it. In _f_o_r_m_a_t_, %%FF indicates the name of the source file, %%LL indicates the line number of the source file, %%NN indicates a newline, and %%%% indicates a percent sign. A sign and digit may be inserted between the percent sign and the `LL', in which case the line number will be adjusted by that amount. If _f_o_r_m_a_t is omitted, the default format is that accepted by the C preprocessor: `##lliinnee %%LL ""%%FF""%%NN'. When using the --LL_f_o_r_m_a_t option, _n_o_t_a_n_g_l_e ensures that all text appears in the same column in input and output. _n_o_u_n_t_a_n_g_l_e ignores this option. --tt_k Copy tabs untouched from input to output, and use tabs for indentation, assuming stops every _k columns. By default, tabs are expanded to spaces with stops every 8 columns. local 4/19/93 2 NOWEB(1) NOWEB(1) --ffiilltteerr _c_m_d Filter the _n_o_w_e_b source through _c_m_d after convert- ing it to tool form and before tangling. _n_o_t_a_n_g_l_e looks for _c_m_d first on the user's PPAATTHH,, then in ||LLIIBBDDIIRR||.. Such filters can be used to add features to _n_o_t_a_n_g_l_e_; for an example see ||LLIIBBDDIIRR||//eemmppttyyddeeffnn.. For experts only. --mmaarrkkuupp _p_a_r_s_e_r Use _p_a_r_s_e_r to parse the input file. Enables use of noweb tools on files in other formats; for example, the nnuummaarrkkuupp parser understands _n_u_w_e_b_(_1_) format. See _n_o_w_e_b_f_i_l_t_e_r_s_(_1_) for more information. For experts only. --aawwkk || --cc || --iiccnn || --iiccoonn || --mmll || --mm33 || --ppaassccaall || --ff7777 || --ff9900 || --tteexx When _n_o_u_n_t_a_n_g_l_e transforms documentation chunks into comments, use the comment format of the lan- guage named. --cc is the default. _n_o_t_a_n_g_l_e ignores these options. --ww_n When _n_o_u_n_t_a_n_g_l_e transforms documentation chunks into comments, create comments on lines of width _n. _n_o_t_a_n_g_l_e ignores this option. WWEEAAVVIINNGG Output from _n_o_w_e_a_v_e can be used in _T_e_X documents that \\iinnppuutt nnwwmmaacc,, in _L_a_T_e_X documents that use the nnoowweebb docu- ment-style option (see _n_o_w_e_b_s_t_y_l_e_(_1_)), and in _H_T_M_L docu- ments to be browsed with _M_o_s_a_i_c_(_1_)_. _N_o_w_e_a_v_e treats code chunks somewhat like _L_a_T_e_X _l_i_s_t _e_n_v_i_r_o_n_m_e_n_t_s_. If the ``@@ '' that terminates a code chunk is followed immediately by text, that text follows the code chunk without a paragraph break. If the rest of the line is blank, _n_o_w_e_a_v_e puts _T_e_X into ``vertical mode,'' and later text starts a fresh, indented paragraph. No page breaks occur in the middle of code chunks unless necessary to avoid an overfull vbox. The documentation chunk immediately preceding a code chunk appears on the same page as that code chunk unless doing so would violate the previous rule. _N_o_w_e_a_v_e inserts no extra newlines in its _T_e_X output, so the line numbers given in _T_e_X error messages are the same as those in the input file. _n_o_w_e_a_v_e has options that dictate choice of formatter and that support different formatting idioms and tools. Basic options are described here; options related to index and cross-reference information are described in the INDEXING AND CROSS-REFERENCE section. local 4/19/93 3 NOWEB(1) NOWEB(1) --llaatteexx Use LaTeX wrapper in aarrttiiccllee style with nnoowweebb style option and page style. (Default) --tteexx Use plain TeX wrapper and the nnwwmmaacc macros. --hhttmmll Format the program for HTML, not TeX or LaTeX. If --nn is not given, use HTML wrapper as well. The output is uninteresting without --iinnddeexx or --xx. The tags <<nnoowweebbcchhuunnkkss>> and <<nnoowweebbiinnddeexx>>, on lines by themselves, produce a list of chunks and an index of identifiers, respectively. If these tags are not present, the list and index are placed at the end of the file. --llaatteexx++hhttmmll Assume documentation chunks are LaTeX, but generate HTML for code chunks, suitably marked so conversion with _l_a_t_e_x_2_h_t_m_l_(_1_) yields reasonable output. A LaTeX wrapper is implied, but can be turned off with --nn. --nn Don't use any wrapper (header or trailer). This option is useful when _n_o_w_e_a_v_e's output will be a part of a larger document. See also --ddeellaayy.. --ffiilltteerr _c_m_d Filters the _n_o_w_e_b source through _c_m_d after convert- ing it to tool form and before converting to _T_e_X_. _n_o_w_e_a_v_e looks for _c_m_d first on the user's PPAATTHH,, then in ||LLIIBBDDIIRR||.. Such filters can be used to add features to _n_o_w_e_a_v_e_; for an example, see ||LLIIBB-- DDIIRR||//nnooxxrreeff..kkrroomm.. _N_o_w_e_a_v_e supports up to four fil- ters; one can get more by shell trickery, for exam- ple, --ffiilltteerr ""iiccoonn..ffiilltteerr || nnooiiddxx"". The --aauuttooddeeffss, --xx, --iinnddeexx, and --iinnddeexxffrroomm options are implemented as filters. --mmaarrkkuupp _p_a_r_s_e_r Use _p_a_r_s_e_r to parse the input file. Enables use of noweb tools on files in other formats; for example, the nnuummaarrkkuupp parser understands _n_u_w_e_b_(_1_) format. See _n_o_w_e_b_f_i_l_t_e_r_s_(_1_) for more information. For experts only. --ooppttiioonn _o_p_t Adds \\nnoowweebbooppttiioonnss{{_o_p_t}} to the _L_a_T_e_X header. Works only with the --llaatteexx option. See _n_o_w_e_b_s_t_y_l_e_(_1_) for values of _o_p_t_. --ddeellaayy By default, _n_o_w_e_a_v_e puts file-name and other infor- mation into the output before the first chunk of the program. --ddeellaayy delays that information until after the first documentation chunk, making act a little bit like the _W_E_B ``limbo.'' The option is local 4/19/93 4 NOWEB(1) NOWEB(1) typically used to enable a user to put a special- ized _L_a_T_e_X \\ddooccuummeennttssttyyllee command and other pream- ble material in the first documentation chunk. This option also forces trailing cross-referencing information to be emitted just before the final chunk, instead of at the end of the document; the final chunk is expected to contain \\eenndd{{ddooccuummeenntt}}.. The --ddeellaayy option implies the --nn option. --tt_k Expand tabs with stops every _k columns. (Default is to expand every 8 columns.) --tt Copy tabs to the output. --vv Print the pipeline on standard error. IINNDDEEXXIINNGG AANNDD CCRROOSSSS--RREEFFEERREENNCCEE When used with _L_a_T_e_X or _H_T_M_L_, _n_o_w_e_a_v_e can provide indexing and cross-reference information for chunks and for pro- gramming-language identifiers. Identifier definitions may be marked by hand using @@ %%ddeeff, or for some languages they may be found automatically using the --aauuttooddeeffss option. This section describes the indexing and cross-reference options; it might well be skipped on first reading. --xx For _L_a_T_e_X_, add a page number to each chunk name identifying the location of that chunk's defini- tion, and emit cross-reference information relating definitions and uses. For _H_T_M_L_, create hypertext links between uses and definitions of chunks. When nnoowweeaavvee --xx is used with _L_a_T_e_X_, the control sequence \\nnoowweebbcchhuunnkkss expands to a sorted list of all code chunks. --iinnddeexx Build cross-reference information (or hypertext links) for identifiers defined by @@ %%ddeeff _i_d_e_n_t_i_f_i_e_r_s Definitions are those found in input files. Requires _L_a_T_e_X or _H_T_M_L_. --iinnddeexx implies --xx;; includ- ing both will generate strange-looking output. _n_o_w_e_a_v_e does not generate cross-references to iden- tifiers that appear in quoted code (@@[[[[...@@]]]]), but it does generate hypertext links. When nnoowweeaavvee --iinnddeexx is used with _L_a_T_e_X_, the control sequence \\nnoowweebbiinnddeexx expands to an index of identifiers. --iinnddeexxffrroomm _i_n_d_e_x Like --iinnddeexx,, but the identifiers to be indexed are taken from file _i_n_d_e_x. See _n_o_i_n_d_e_x_(_1_)_. --aauuttooddeeffss _l_a_n_g Discover identifier definitions automatically. Code in chunks must be in language _l_a_n_g. Permissi- ble _l_a_n_gs vary but may include tteexx or iiccoonn.. local 4/19/93 5 NOWEB(1) NOWEB(1) Useless without --iinnddeexx,, which it must precede. --sshhoowwaauuttooddeeffss Show values of _l_a_n_g usable with --aauuttooddeeffss. EERRRROORR MMEESSSSAAGGEESS If _n_o_t_a_n_g_l_e or _n_o_w_e_a_v_e encounters a chunk name within doc- umentation, it assumes that this indicates an error, usu- ally misspelling ``<<name>>=''. Other error messages should be self-explanatory. It is incorrect to refer to a chunk that is never defined, but it is OK for chunks to be defined and not used. FFIILLEESS |LIBDIR|/markup markup preprocessor |LIBDIR|/unmarkup inverts markup |LIBDIR|/nt notangle proper |LIBDIR|/finduses find uses of identifiers for index |LIBDIR|/noidx generate index and cross-reference info |LIBDIR|/totex back end to emit _T_e_X or _L_a_T_e_X |LIBDIR|/tohtml back end to emit HTML |TEXINPUTS|/nwmac.tex formatting _T_e_X macros |TEXINPUTS|/noweb.sty use in _L_a_T_e_X documents; see _n_o_w_e_b_s_t_y_l_e_(_1_) SSEEEE AALLSSOO _c_p_i_f_(_1_)_, _n_o_d_e_f_s_(_1_)_, _n_o_r_o_o_t_s_(_1_)_, _n_o_w_e_b_(_1_)_, _n_o_i_n_d_e_x_(_1_)_, _n_o_w_e_b_s_t_y_l_e_(_1_)_, _n_o_w_e_b_f_i_l_t_e_r_s_(_1_) BBUUGGSS _n_o_t_a_n_g_l_e and _n_o_u_n_t_a_n_g_l_e fail if names used on the command line contain single quotes. Ignoring unused chunks can cause problems; if a chunk has multiple definitions and one is misspelled, the misspelled definition is silently ignored. _n_o_r_o_o_t_s_(_1_) can be used to catch this mistake. _n_o_w_e_b requires the new version of _a_w_k_, assumed to be called _n_a_w_k_. DEC _n_a_w_k has a bug in that that causes nnoowweeaavvee to fail to translate braces correctly. GNU _g_a_w_k is reported to work. DEC _s_h has a bug that causes the --ffiilltteerr option to fail whenever the filter command contains more than one word. The default _L_a_T_e_X pagestyles don't set the width of the boxes containing headers and footers. Since _n_o_w_e_b code paragraphs are extra wide, this _L_a_T_e_X bug sometimes results in extra-wide headers and footers. The remedy is to redefine the relevant ppss@@** commands; ppss@@nnoowweebb in nnoowweebb..ssttyy can be used as an example. _l_a_t_e_x_2_h_t_m_l_(_1_) mangles some source files. local 4/19/93 6 NOWEB(1) NOWEB(1) _n_o_w_e_a_v_e has too many options, and this man page is too long. AAUUTTHHOORR Norman Ramsey, Bellcore. Internet address nnoorr-- mmaann@@bbeellllccoorree..ccoomm. Noweb home page at ffttpp::////bbeellllccoorree..ccoomm//ppuubb//nnoorrmmaann//wwwwww//nnoowweebb//iinnttrroo..hhttmmll. local 4/19/93 7